<div align="center">
  <a href="https://mintlify.com">
    <img
      src="https://res.cloudinary.com/mintlify/image/upload/v1665385627/logo-rounded_zuk7q1.svg"
      alt="Mintlify Logo"
      height="64"
    />
  </a>
  <br />
  <p>
    <h3>
      <b>
        Mint
      </b>
    </h3>
  </p>
  <p>
    <b>
      Open source docs builder that's beautiful, fast, and easy to work with.
    </b>
  </p>
  <p>

![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen?logo=github) [![Tweet](https://img.shields.io/twitter/url?url=https%3A%2F%2Fmintlify.com%2F)](https://twitter.com/intent/tweet?url=&text=Check%20out%20%40mintlify)

  </p>

  <p>
    <a href="https://mintlify.com" target="_blank">
      <img
        src="https://mintlify.com/assets/og.png"
        alt="Mintlify"
        width="100%"
      />
    </a>
  </p>
</div>

# Mintlify's markdown parser

**@mintlify/mdx** is a thin layer on top of [next-mdx-remote](https://github.com/hashicorp/next-mdx-remote) that provides a better developer experience for Next.js users by adding support for syntax highlighting.

## Installation

```bash
# using npm
npm i @mintlify/mdx

# using yarn
yarn add @mintlify/mdx

# using pnpm
pnpm add @mintlify/mdx
```

## Examples

### Next.js pages router

[You can check the example app here](https://github.com/mintlify/mdx/tree/main/examples/pages-router).

1. Call the `getCompiledMdx` function inside `getStaticProps` and return the `mdxSource` object.

   ```tsx
   export const getStaticProps = (async () => {
     const mdxSource = await getCompiledMdx({
       source: "## Markdown H2",
     });

     return {
       props: {
         mdxSource,
       },
     };
   }) satisfies GetStaticProps<{
     mdxSource: MDXCompiledResult;
   }>;
   ```

2. Pass the `mdxSource` object as props inside the `MDXComponent`.

   ```tsx
   export default function Page({
     mdxSource,
   }: InferGetStaticPropsType<typeof getStaticProps>) {
     return <MDXComponent {...mdxSource} />;
   }
   ```

3. Import `@mintlify/mdx/dist/styles.css` inside your `_app.tsx` file. This file contains the styles for the code syntax highlighting.

   ```tsx
   import "@mintlify/mdx/dist/styles.css";

   import { AppProps } from "next/app";

   export default function App({ Component, pageProps }: AppProps) {
     return <Component {...pageProps} />;
   }
   ```

### Next.js app router

[You can check the example app here](https://github.com/mintlify/mdx/tree/main/examples/app-router).

1. Call the `getCompiledServerMdx` function inside your async React Server Component which will give you the `frontmatter` and `content`.

   ```tsx
   import { getCompiledServerMdx } from "@mintlify/mdx";

   export default async function Home() {
     const { content, frontmatter } = await getCompiledServerMdx({
       source: `---
         title: Title
         ---
   
         ## Markdown H2
       `,
     });

     return (
       <article className="prose mx-auto py-8">
         <h1>{String(frontmatter.title)}</h1>

         {content}
       </article>
     );
   }
   ```

2. Import `@mintlify/mdx/dist/styles.css` inside your `layout.tsx` file. This file contains the styles for the code syntax highlighting.

   ```tsx
   import type { Metadata } from "next";
   import "@mintlify/mdx/dist/styles.css";

   export const metadata: Metadata = {
     title: "Create Next App",
     description: "Generated by create next app",
   };

   export default function RootLayout({
     children,
   }: {
     children: React.ReactNode;
   }) {
     return (
       <html lang="en">
         <body>{children}</body>
       </html>
     );
   }
   ```

## APIs

Similar to [next-mdx-remote](https://github.com/hashicorp/next-mdx-remote), this package exports the following APIs:

- `getCompiledMdx` - a function that compiles MDX source to MDXCompiledResult.
- `MDXComponent` - a component that renders MDXCompiledResult.
- `getCompiledServerMdx` - a function that compiles MDX source to return `content` and `frontmatter ` and should be used inside async React Server Component.
- `MDXServerComponent` - a component that renders `content` and `frontmatter ` and should be used inside async React Server Component.

### getCompiledMdx

```tsx
import { getCompiledMdx } from "@mintlify/mdx";

const mdxSource = await getCompiledMdx({
  source: "## Markdown H2",
  mdxOptions: {
    remarkPlugins: [
      // Remark plugins
    ],
    rehypePlugins: [
      // Rehype plugins
    ],
  },
});
```

### MDXComponent

```tsx
import { MDXComponent } from "@mintlify/mdx";

<MDXComponent
  components={
    {
      // Your custom components
    }
  }
  {...mdxSource}
/>;
```

### getCompiledServerMdx

```tsx
import { getCompiledServerMdx } from "@mintlify/mdx";

const { content, frontmatter } = await getCompiledServerMdx({
  source: `---
    title: Title
    ---

    ## Markdown H2
  `,
  mdxOptions: {
    remarkPlugins: [
      // Remark plugins
    ],
    rehypePlugins: [
      // Rehype plugins
    ],
  },
  components: {
    // Your custom components
  },
});
```

### MDXServerComponent

```tsx
import { MDXServerComponent } from "@mintlify/mdx";

<MDXServerComponent
  source="## Markdown H2"
  components={
    {
      // Your custom components
    }
  }
/>;
```

<div align="center">
  <p>
    <sub>
      Built with ❤︎ by
      <a href="https://mintlify.com">
        Mintlify
      </a>
    </sub>
  </p>
</div>
